Readme for !Elc2

PLEASE NOTICE: you have to rename one of the !Run.... files to !Run. This has been done to avoid overwriting in case of upgrades, and to give you a choice: norally there is a sound system aailable and you can choose !Run_Default to rename to !Run, when it should run on an Archimedes choose !Run_Archi, when on Risc_Os_Linux_Binary (under Linux, see https://github.com/TimothyEBaldwin/Risc_Os_Linux_Binary) ther is no sound so use the version without sound.

This is an Electron emulator for anything (as host computer) from Archimedes upto RaspberryPi 4B+. E.g. Archimedes, RiscPC, A9home, Iyonix, Beagleboard XM, Raspberrypi.
Why Electron? Long ago, I tried to run a Mandelbrot program with !6502Host but it failed. So, wrote an emulator to find the mistake -it was a forgotten CLD instruction. Recently I thought to finish that emulator, but it took me longer than expected. The 6502 instruction set is not that simple to emulate, because of the exact timing requirements on which some games and demo's depend. In the Electron you cannot trust the timings from books, because its CPU is stalled by the other chip, its ULA. My emulation still is far from perfect. For the time being, I left all the diagnostic stuff in the emulator (so you can singlestep, view the contents of Sheila (=the IOC registers), the pointers in cassette and 1772, set traps for instructions or memorylocations, optimize the grouping of instructions in order to fit better in caches, etc.)
What does this emulator require from its host system?
A Risc OS ARM machine with 2700K wimpslot or more. !Anymode for RaspberryPi. Using this, the program can singletask without too many problems.
There is a slight problem on Beagleboard when returning from singletasking; it needs an extra press on the F12 button and then a press on another button e.g. Return. The fact that BB has a different colourdepth system compared to e.g. Iyonix, A9home, RPi could be a culprit but to be fair, I have no idea. The extra F12/Return presses work, as far as I can see. I als saw it on some Raspberrypi versions.
On an Archimedes, even equipped with an ARM3, the emulation is sluggish. The program tries to be exact, every screenline (every 64 /usec) three screenline-update interrupts are done. Even if nothing has to be translated to the screen of the Archimedes, the overhead in terms of ARM instructions is considerable. Moreover, the ARM3 has a small cache that may be too small for the task. From RiscPC with ARM710, things begin to get more acceptable. The 4 Megabyte on most Archimedes is just enough, but you have to limit the number of floppies to one: make sure that wimpslot is -min 2700K -max 2700K. And, use a crunched version of !Runimage (!Runimage').
For sound, SharedSound is used. The module I use as an intermediate handler (RBMemMgr) uses a dynamic area to transfer sound data, but Archimedes is unaware of the Dynamic Area concept. On RISC_OS_Linux_Binary there is no sound because it's not ready there yet. So it's best to comment away the lines with SharedSound in the !Run file on these machines. Either by removing the 2 lines or by placing an | before the lines. It then complains about not being able to play sound, but ignore that. If and when I understand how 8-bit sound works (I don't), an Electron 'voice' should be added for the Archimedes.
I have some code lingering here to supply something that reads (hardware) DFS and ADFS diskettes into images on an Archimedes, and code to convert sampled RIFF waves from audio-cassettes into UEF's. But atm the user interfaces are too user-unfriendly and they cannot handle some border-cases reliably, e.g. dropouts on tapes. Code to remediate such failings should be added before I can release these additional programs. Luckily, by far the most diskettes and UEFs are already available on e.g. www.acornelectron.co.uk or on archive.org.

Configuration.
There is a possibility that you need to configure everything the first time you use this. Choose Config on the iconbar menu, and when everything is as desired then click Save. If the program can find $.!Boot.Choices then a directory 'Elc2' is generated there, and the configuration file is written. If the mainwindow is open in the meantime, click RESET on the left pane so that the chosen values can be effectuated, Saving the configuration choices should be done explicitly, so click on Save in the Configuration window. Default, Filing systems are not enabled; DFS is the most usable because it leaves PAGE at &E00 (at least, in the DFS rom in 'ROMS')
Extra guidance can be found by activating !Help, the RiscOS application for interactive help. It's living behind the iconbar icon Apps, it's an application in ROM so you will not find it in $.Apps or $,Utilities.

Media:Disks.
Both ADFS and DFS can be used. Either of the two can be chosen via Config. The DFS version is one with not only DFS in a ROM on the cartridge but also 4 K of RAM, and this made it possible to keep PAGE low, at &E00. ADFS takes a large bite of RAM for disc management out of the already small amount of RAM available, causing many tape-based programs to lack sufficient space to run. ADFS has its PAGE at &1D00, but this DFS has it at &E00.
To choose cassette as your storage medium, type *TAPE.
For DFS, the command to 'mount' a disk is *DRIVE <n> (with <n> is 0,1,2 or 3), and *EXEC !BOOT or CHAIN"!BOOT" to start things up. Provided there is a !Boot file on the DFS diskette. Otherwise use *EXEC <name> or CHAIN"<name>" with <name> is the file to run. Of course, CHAIN is meant to load and run BASIC files. Consult the manuals on the 'Net if your recollection is rusty, like mine.
For ADFS, these commands are (for mounting) *MOUNT <n> (<n> is a drive number, i.e. 0,1,2 or 3) and (again) *EXEC !BOOT or CHAIN"!BOOT" etc.
If there is no !BOOT file on diskette (catalogue the disc contents with *CAT to see what's there) but only separate files with a name e.g. SHYGGYS, then do *EXEC SHUGGYS or CHAIN"SHUGGYS" - (only 'CHAIN' will work in this case as SHUGGYS is a BASIC program, for the game Shuggys Garden)
Cataloguing is done by using *CAT, sometimes *EX also works.
For formatting diskettes, usually a utilities diskette is needed (such as the ADFS Welcome diskette). From the accompanying documentation you will no doubt be able to figure what parameters to pass with these commands.
The number of usable diskettes (one or two) is selectable in Configure (iconbarmenu of !Elc2). Note that in those days, numbers 2 and 3 were on the flipside of diskettes 0 and 1. In Configure you can also determine the space for cassette UEFs. The program uses only memory that is provided according to the !Run file (*WimpSlot -min.. -max ..), and uses no dynamic areas, except for sharedsound if the host machine can handle that. Avoiding dynamic areas is due to the design decision that this !Elc2 program should also run on Archimedes or comparable with Riscos 3.10, and RO3.10 is unaware of Dynamic Areas. 
The size of !RunImage can be reduced by crunching to appr. 270K so there's more memory left for diskettes, each requiring 1000000 bytes, and cassette. Cassette gets the spare space after program, workspaces, diskettes are subtracted from the wimpslot. The wimpslot is adaptable with an text editor like !StrongEd or !Zap. For a 4 Mb Archimedes, a 2700K maximum wimpslot and a crunched !RunImage' are required. The BASIC editor !Reggraph can do this crunching for you: select all options in the Utilities-->Crunch menu except '.. in DATA lines too,' and 'Omit unused labels' and import the Excludefile (from !Elc2 directory). Then crunch and save the resulting program.
Under the menubutton-mouseclick on an empty floppybay is the possibility to create a pre-formatted floppie. This saves you the trouble of looking for a utilities disc and finding out the command to use.

Media:UEFs
The UEFs available on Internet usually are zipped files. They cannot be used directly but they have a characteristic 'word' to begin with, (&00088B1F) that !Elc2 recognises. If a suitable unzip facility is there, e.g. if !SparkFS or !SparkPlug are active, or also the free version of !SparkFS in $.Utilities, then !Elc2 can have your UEF unzipped on-the-fly. Infozip also seems to be possible but I have not tried this myself. You can alse drag the zipped file onto !SparkFS, and another file will appear whose name usually ends on '00'. To check, load this resulting file into a text editor and see if it begins with 'UEF File!'. If yes, chances are that !Elc2 can use this file as a cassette UEF. Non-zipped UEFs always begin with 'UEF File!' (without the '' -s!)
As long as there is some module loaded that understands *unzip <inputfile> <outputfile> then !Elc2 probably can load these zipped UEF's too. Otherwise, find something that unzips them for you.
UEF's (Unified Emulator Format) is a description protocol to decode/encode the sounds on cassettes into a format usable as a form of imagefile, to use with emulators. It has a header, and then a series of [ descriptor word, length, datablock] . Generally, the datablocks are already decoded into bytes. Floppy contents can also be encoded into these UEFs. Hopefully my implementation of the decode algorithm is sufficient to handle most UEFS that are available for the Electron. The UEF file is for the emulator what a cassette-tape is for a real Electron. Drag the UEF file onto the Cassette sprite on the left pane and a window should open with the contents of the UEF. You can position the cassette-filepointer to the start of one of these files by clicking on the little wheels, this way you can spool forward or backward. There is an option under the mouse-menu button to clear the contents of the cassette, and a menu button in the right upper corner that leads to a menu where you can select each file individually, or all of them, and a further menu option from this first menu to save it as a file, an UEF or a RIFF Wave.
When you have dragged an UEF into the 'cassette', then you can make the cassette the current filingsystem with *TAPE. I.e. type *TAPE into the emulator's main window. The files can be catalogued with *CAT, loaded with *LOAD <filename> <address in hexadecimal>, or executed with *EXEC (if it's an executable file such as !Boot sometimes - '*EXEC !BOOT'), or loaded and immediately run as a BASIC file with CHAIN "<filename>". If you intend to CHAIN the very next file on cassette, then CHAIN "" is all it takes. For executable files. */ often does the trick with the file where the cass pointer points to. It is very common to start cassette-based games with CHAIN "".

Media: Dragging files directly onto the Main window.
The last method to load/run files is, by dragging them directly onto the Main window. If the emulator is not entirely sure what to do with it, a dialogue window is openend with the choices Execute, Save to current directory of Just Load. It is possible that the load- and execution address have to be entered, in hexadecimal digits. Generally, for a tape system or DFS the load address is &E00, for ADFS it's &1D00. If it's an executable the execution address is often the same as the load address, but be prepared for surprises. If it's a BASIC file, the execution address should be &8023 as that is the execution address that is recognised for BASIC files. 

The Pane at the lefthandside to the Main window.
Short description of the options in this pane (there is also interactive help if !Help is activated).
Keyboard: Toggle American, Great Britain and Electron keyboard with Select (left button) mouseclick. So if you have e.g. an American keyboard you can just press the keys as you are used to, e.g. * is Shift+8. The Electron keyboard is very unlike modern keyboards, for instance (unlike the BBC micro) it had no dedicated function keys but FN1, FN2.. were done by pressing FN/CapsLock and 1,2,3.. . Many games expect /? and :* (to the left of R.shift and Return), so it's useful to be able to use the ancient Electron layout for these. Right/Adjust click on Keyboard icon produces a window with the Electron key layout. Note that the Electron had only one Ctrl key, and the two Shift keys were interconnected so in effect there also was only one Shift key. (it was a very simple system, there was no dedicated keyboard chip but the keyboard was treated as a 16-kB ROM, each of the 14 adress bits were probed in succession, the 4-bit result then evaluated)
In American and GB keyboard, the function keys F1..F9 should simulate the simultaneous FN/CapsLock + 0..9 keypresses; CapsLock on its own simulates Shift+CapsLock (ie. toggles CapsLock status) and Tab is chosen as a replacement for pressing Fn/CapsLock for entering singlekeypress-keywords. E.g. Tab+E produces 'ELSE'. 
Monitor: What was called 40 years ago a 'monitor' was a program that monitored / kept an eye on/ let you inspect the output of the running program. This one also lets you inspect the inner workings of the 'Electron', you can singlestep things or make bigger steps. The interactive guidance of !Help reveals it all. The program can also recall the last 22 steps so that you can inspect a number of preceding steps.
Reset: Does everything that this name says. Most, but not all, changes in Configure get activated only after a reset (Choice of singletasking screensize, for instance, does not require reset).
Sound: Select mousebutton silences or turns on the sound, Adjust mousebutton opens a window with an amplitude slider. Atm it only works with Sharedsound and not on an Archimedes (because Archimedes is unfamiliar with Dynamic Areas and DA's are used/required to transfer the Sharedsound data) and not on the Linux RISC_OS_Linux_Binary, because sound is not working there yet. It would be possible to add 8-bit sound for Archimedes if only I knew how. I'm unable to grasp how 8-bit sound works. Besides, Archimedes is just too slow to run !Elc2 so, why bother.
Speed: Pressing or sustaining pressure with Adjust mousebutton turns the emulation speed up. Tapping Select on this icon, resets speed to 1X. Can help to reduce time for loading-in UEF cassettetape files, or playing Acornsoft Chess (or anything that can need a bit more of speed).
Cassette: Opens if you drag an UEF file on it. Could also be a zipped UEF if something that understands *unzip is active at the same time. The menu-icon in the righthand upper corner gives access to save-options, among others as a Riff wave. The wavefiles that are produced can be played with e.g. !Playit or !DigitalCD; then it's possible to connect the audio-out of your hostmachine to the DIN audio-in of a real Electron, BBC micro, Master. The wave amplitude and the relative phase of 2400 vs 1200 Hz are adaptable, the relative amplitude of 1200/2400 not (yet). For my Electron, amplitude must be max and the 2400Hz phase a little to the right. Mater is OK with less amplitude. The wavesave is not machine-specific. Not all outgoing signalstrengths of host computers are the same, Iyonix is a little weak and clipped (which in this case is not a problem), A9home is strong, RiscPC and RPI are OK.
Plus-1: Clicking opens a window with two cartridgeslots as on the original Plus-1. Configure its existence in Configure menu-option. ROM cartridges can be dragged on it (some are available on stairwaytohell). Clicking Reset notices the presence of such a rom. Sometimes (games, demo-cartridge) the ROM takes over the machine but other ROMS, e.g. languageROMs like Pascal must be invoked explictly. If there is a twin-ROM (e.g. Pascal 1 and 2) the emulator expects the twin ROM in the same directory as the first twin-ROM. By pressing menu mousebutton on the ROM you are given the option to remove a ROM. When removed, at the next Reset, the ROM is no longer inserted then.
Printer and joystick via USB-Joystick module do not work yet; but it should be possible to use the mouseposition as analogue joystick input in Singletasking. If this option is chosen in Configure and a Reset is done, some further choices can be made via the Iconbar menu-->Joystick. I can't say that this works very good, YMMV.
Floppies - the icon with the two blue diskettes. Opens a window with two diskettebays. If the bay is empty there is a menu to create a formatted floppy.  You can also drag dsd, ssd or adf/ade floppies on a diskettebay or on the pane-icon. The contents of these ssd/dsd etc. images is inspected; filetypes and /ssd etc. suffixes are not looked into. For adfs disks, there are 2 ways in which the sides can be ordered, sequentially and serially. If the emulator suspects that the ordering is incorrect, it gives you the option to correct it. But you can experiment until the emulator recognises them without disc map errors, e.g. with *CAT. DFS discs also have two variations; one is, tracks of side 0 and 1 interleaved, second is, sides interleaved. The program now recognises these two possibilities.
Singletask. What the name says. It's best to choose 640X512 (in Configure). RaspberryPi with Anymode accepts this, old Acorn machines do this too. More modern machines sometimes have a monitor (in the sense of that rectangular jardware LCD displaything) that can no more display 640X512, so as a second option there is 800X600 in the hope that more machines accept it. And a third one, 640X480. The choice is made in Iconbarmenu-->Configure. Returning from Singletasking is done with F10,F11,F12,AltL or AltR. Select-mousebutton click on the Singletasking icon goes into Singletasking, Adjust saves what's on screen as a sprite in <Elc2$Dir>.DUMP.
In most circumstances, the emulator first constructs an intermediate icon and then, every 1/50 sec or so, writes this to the screen. In Configure, you can also choose to have the intermediate-icon and/or the singletasking MODE in 16 colours; in particular the speed on an Archimedes benefits from this. Some host machines (Iyonix, A9home, RPI) cannot singletask in 16-colour, the emulator automatically recognises this (hopefully). 
TEST ON/OFF. Clicking Adjust opens a TEST window, with various diagnostic things. For instance, how often some instructions come along can be saved, or traps on various instructions or addresses can be set. Adjust-Clicking on the Opcodes icon re-arranges the instruction execution codelets so that the most frequent ones are grouped together (but let the emulator do enough instruction-exec time in this state to get an idea what is frequent and what is seldom). All these tests do, however, impede the execution speed no end, so normally leave TST OFF. The RAM timings (a similar option is there under the iconbaricon menu) can change the RAM-speed into BBC league, some very sluggish (BASIC) files in modes 0..3 get notably faster. For instance type-in games that were meant for the BBC but were unplayable-slow on the Electron, too. If no path for a save-action e.g. 'save ASM code' is given, then these things are saved to <Elc2$Dir>.DUMP.

Savestate.
It is possible to save almost the complete state of the emulator and retrieve it next time. Typically this is saved as a directory that you can give a name by yourself; and in that directory there is a file 'savestate' and, where applicable, UEF- or Floppy images, or pointers to them. The savestate file is a textfile; the contents of Electron RAM 0-&7FFF, DFS RAM (optionally) and resident-variables (appr. 1300 bytes) are base-64 coded and you should not change these. Moreover, there is an option in Configure where you choose to save the state when quitting and resume when starting-up again. In this latter case, the savestate directory is saved in <Elc2$Dir>.DUMP. A savestate directory or a separate savestate file can be dragged on the open mainwindow or on the iconbar icon; hopefully the state as saved is retrieved then. The emulator would very much like you to not change the relative location of the diskettes or UEFs from where they were when the state was saved; the savestate file mentions their location and the retrieve mechanism relies on their presence there. If something goes wrong then the emulator hopefully just resets and should not crash. To revive an old state just drag the savestate file or the directory wherein it lives, o the emulator (or on the iconbar icon). There are some example savestates in 'saved'. Most of them expect DFS as the active filing sytem, this can be activated in Configure.

More Files, DFS/ADFS and UEF files.

https://archive.org/details/Acorn_Electronic_TOSEC_2012_04_23
(for completeness - the Archimedes and BBC equivalents are -
https://archive.org/details/AcornArchimedes_201809
https://archive.org/details/Acorn_BBC_TOSEC_2012_04_23
)
www.acornelectron.co.uk.  So to see, downloadable files and DVD's or a 64 Gb USB stick can be ordered with more than you can play or read in a lifetime.
The Stairway To Hell: www.stairwaytohell.com
On www.stardot.org.uk there are notifications concerning software, games, demo's too.
Some items available from www.bbcmicro.co.uk can also be run on an Acorn Electron.

Almost all files in the Disks/ROMS/SSD/Saved/UEF etc directories are from 'third parties', but they all are available on the Internet. I hope that the rightful owners of them don't object to inclusion of these; the presence of them is only meant to help you, the user, on the way and an illustration of what the humble Electron was capable of, thanks to the creative and ingenious programming of the writers.
What more?
A long list of wishes. For the time being I think I spent too much time on this emulator already, and as there are good BBC emulators out there (e.g. have a look at https://virtual.bbcmic.ro) the big question is why one should spend time on an emulation of a machine that has only half the speed, no MODE 7, only one sound channel, etcetera.
Anyhow the project has learnt me a lot.

enjoy 

Jan de Boer jandeboer@telfort.nl
www.tellima.nl


